feat: honor thread context classloader when loading custom normalizers and generators - #24617

A custom NORMALIZER_CLASS normalizer could fail to load, especially under the Gradle plugin's process worker isolation:

1. OpenAPINormalizer.createNormalizer used bare Class.forName(String), which resolves against the classloader that loaded openapi-generator core, not any user-supplied classpath.
2. The Gradle plugin never called classpath.from(...) in either isolation branch. Under process isolation this is fatal: the forked JVM has zero visibility into anything not explicitly forwarded. Under classloader isolation it was merely fragile: since the worker runs in the same JVM, a custom normalizer could work by accident if it happened to already be reachable through the existing classloader hierarchy (e.g. stuck on the buildscript classpath), but this was never a supported or documented mechanism.

Changes

Core (OpenAPINormalizer.java)

• createNormalizer now resolves the class via the current thread's context classloader (TCCL) first (which Gradle's Worker API sets to include user classpath), falling back to the original defining classloader for backward compatibility.
• Failure messages are split by cause: ClassNotFoundException gets classpath guidance, other reflective failures (bad constructor, instantiation errors) get a distinct, accurate message.

Gradle plugin

• Added generatorClasspath (file collection) and an openApiGeneratorExtra resolvable configuration, both forwarded to the worker in processIsolation and classLoaderIsolation. Users can now supply a custom normalizer jar via normal Gradle dependencies or file collections.
• Documented the classpath requirement in the openapiNormalizer KDoc, README, and customization docs.

Tests

• Core: added unit tests covering TCCL resolution, TCCL-null and TCCL-miss fallback, and the clearer error message.
• Gradle plugin: added GeneratorClasspathIsolationTest covering both classpath mechanisms under both isolation modes, plus a negative control. Positive tests assert a marker file written by the fixture normalizer's normalize() to directly prove it ran, not just that the build succeeded.

Compatibility

Fully backward compatible. No NORMALIZER_CLASS set, or normalizer already visible on the default classpath: unchanged behavior. New properties default to empty/unset.

PR checklist

• Read the contribution guidelines.
• Run the following to build the project and update samples:

  ./mvnw clean package || exit
  ./bin/generate-samples.sh ./bin/configs/*.yaml || exit
  ./bin/utils/export_docs_generators.sh || exit
  

  (For Windows users, please run the script in WSL)
  Commit all changed files.
  This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
  These must match the expectations made by your contribution.
  You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
  IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

Summary by cubic

Prefer the thread context classloader when loading custom NORMALIZER_CLASS and custom generators, and forward user classpaths in the Gradle plugin for both isolation modes. Adds precise, tool-agnostic errors, better generator discovery, updated docs, and tests that prove the classes actually run.

• New Features

  • Core: OpenAPINormalizer now resolves via the thread context classloader with a safe fallback and clearer errors (classpath/not‑found vs bad constructor). CodegenConfigLoader uses the context classloader; getAll() merges/de‑dupes across classloaders; forName() returns precise errors for classpath/not‑found, incompatible Java version, static initializer failures (including subsequent NoClassDefFoundError), linkage errors, and bad constructors/implementations.
  • Gradle plugin: adds openApiGeneratorExtra and a generatorClasspath property; both are forwarded to the worker classpath for workerIsolation process and classloader. README/KDoc document classpath requirements for NORMALIZER_CLASS and custom generators by name/FQCN. Tests cover both isolation modes, generator by FQCN, negative controls, and execution proven via marker files.

• Migration

  • When using a custom NORMALIZER_CLASS or a custom generator (by name/FQCN) with the Gradle plugin, add it to openApiGeneratorExtra (preferred) or generatorClasspath, e.g. dependencies { openApiGeneratorExtra("com.acme:my-normalizer:1.0.0") } or openApiGenerate { generatorClasspath.from(files("libs/my-generator.jar")) }.

^{Written for commit c76fd40. Summary will update on new commits.}